APIs for Programmatic Access¶
Identities are present everywhere and in every piece of IT. Apart from the passwords, keys, and other credentials used by humans, every organization has to deal with a lot of machine identities, credentials embedded on scripts and applications, and so on. Securden provides APIs for programmatic access of the data stored in the product. Scripts, applications, and configuration files that require credentials can access the Securden database and fetch the data, thus eliminating the dangerous practice of hard-coding of credentials. API access is regulated through a token-based authentication mechanism.
To programmatically access an account through API, you need an URL and the Auth Token. The token can be a static one or dynamic and valid for a specified time duration or forever. The access can be restricted from specific IP addresses or FQDNs. Also, tokens can be applicable only for a specific list of operations.
As mentioned above, you require two things for API access:
- Authentication token
- Access URL
You need to create the authentication token in the GUI and then construct the URL referring to our API reference guide. You need to supply the URL and the Auth Token to the calling application.
How to create the authentication tokens for APIs?¶
To create tokens for APIs, navigate to Admin >> API Access >> Authentication Token for API Access section.
In the GUI that opens, click the button Create Token.
In the GUI that opens, you need to enter the following information:
Token name and description¶
Enter a name for the token being created. This API Reference Name helps you uniquely identify the token when using it in APIs. A description will help in tracking the purpose of the token.
Token access restrictions¶
If you want to restrict the token usage only from specific IP addresses, you may enter the same in the field “Allow API requests from the following IPs/FQDN”. You can enter individual IP addresses in comma separated form or an IP range or FQDNs or CIDR notations.
Examples:¶
Specific IP Address: 191.224.1.22
IP Range: 224.1.1.10:224.1.2.1
CIDR Notation: 192.168.1.30/24
Token type¶
You can choose to create a static token or a dynamically changing one. Select your choice Static or Dynamic as required.
Token lifetime¶
You can also decide about the lifetime of the token being created. Static tokens can be created with a permanent validity Set to Never Expire or can be created to be valid for a predefined date and time. Select the option Valid Upto and set the validity date. Dynamic token will have a short lifespan in minutes.
Token scope¶
You can define the scope of the token being created by restricting the operations for which the token generated here would be applicable. In other words, the API, with this token, cannot be used for operations other than the ones selected in scope. To define the scope, select the required operations under Token Applicability.
Create the token and copy the static token¶
After defining the scope, proceed to create the token.
If you have chosen the type Static, you will be prompted to copy the token to the clipboard. The token will be displayed only once and you can’t refer to that again if you don’t copy it.
Getting dynamic tokens¶
Dynamic auth tokens can be obtained programmatically. Typically, you will obtain it as explained below. You will have to pass the credentials to access Securden as arguments.
GET /api/get_auth_token
Input data (arguments): login_name (String), password (String), domain_name
(Default authentication will be local)
Example (if you are using Curl):
curl -k -X GET
"https://pamdemo.com/api/get_auth_token?login_name=admin&password=admin&domain_name=xyz"
Edit, Delete, Update, Regenerate Tokens¶
You can use the Actions column on the APIs page to delete the tokens that are no longer needed. Similarly, you can edit the static tokens and extend their lifetime (validity period). In such cases, you will have to update and regenerate the token.
Token creation is the first step in API access. You need to construct the URL for use by applications, scripts, and configuration files.
Constructing the URL for API Access¶
To programmatically access an account through API, you need a URL with the Auth token. You have created the auth token through the steps detailed above. You can create the URL by following the steps detailed in the API Help Documentation present in Admin >> API Access >> Authentication Token for APIs. The documentation explain how the URL is to be constructed and the arguments to be passed for various operations.
